/*
 * Copyright 2010 Francisco Modesto
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.googlecode.gwt.tinyaop.client;

import java.lang.annotation.Annotation;

/**
 * A <code>MethodDescriptor</code> provides information about a single method
 * on a class or interface.<br>
 * <code>MethodDescriptor</code>s are unique. It is safe to use them in a Map
 * or test them with '=='.
 */
public interface MethodDescriptor {
  /**
   * Returns the <code>Class</code> object representing the class or interface
   * that declares the method represented by this <code>MethodDescriptor</code>
   * object.
   * @return the owner type for the method this object represents
   */
  public Class<?> getDeclaringType();
  
  /**
   * Returns the name of the method represented by this <code>Method</code> 
   * object, as a <code>String</code>.
   * @return the name for the method this object represents
   */
  public String getName();
  
  /**
   * Returns a <code>Class</code> object that represents the erased return type
   * of the method represented by this <code>MethodDescriptor</code> object.
   * @return the return type for the method this object represents
   */
  public Class<?> getReturnType();
  
  /**
   * Returns an array of <code>Class</code> objects that represent the erased
   * parameter types, in declaration order, of the method
   * represented by this <code>MethodDescriptor</code> object.  Returns an array
   * of length 0 if the underlying method takes no parameters.
   * @return the parameter types for the method this object
   * represents
   */
  public Class<?>[] getParametersType();

  /**
   * Returns this element's annotation for the specified type if such an annotation
   * is present, else null.
   * @param annotation the Class object corresponding to the annotation type
   * @return this element's annotation for the specified annotation type if present
   * on this element, else null
   */
  public <T extends Annotation> T getAnnotation(Class<T> annotation);
}
